/*
 * Copyright 2007-2008 by Matthias Buch-Kromann <mbk.isv@cbs.dk>.
 * 
 * This file is part of the Open-source Dependency Toolkit (OSDT),
 * see http://code.google.com/p/open-source-dependency-toolkit. 
 * 
 * The OSDT is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published
 * by the Free Software Foundation, either version 3 of the License,
 * or (at your option) any later version.
 *
 * The OSDT is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with the OSDT in the files COPYING and COPYING.LESSER. If
 * not, see http://www.gnu.org/licenses.
 */

package org.osdtsystem.functions;

import java.util.List;
import org.osdtsystem.graphs.GraphAccessor;
import org.osdtsystem.values.Location;
import org.osdtsystem.values.Property;

/**
 * The public interface for a function that returns a function value with class V. 
 * @param <V> the class of the function value
 * @author Matthias Buch-Kromann <mbk.isv@cbs.dk>
 */
public interface Function<V> extends Property {

    /**
     * Recompute the function value associated with the function. 
     * @param caller the calling function
     * @param context the evaluation context
     * @param accessor the graph accessor which provides an interface between the function and the graph
     * @return the new function value
     */
    public List<V> functionValue(
        LocalFunction<?, ?> caller,
        FunctionContext context,
        GraphAccessor accessor);
    
    @Deprecated
    public List<V> functionValue(Location location, GraphAccessor accessor);
    
    /**
     * List of all subfunctions called by this function.
     * @return list of subfunctions called by this function
     */
    public List<Function<?>> subfunctions();

    public String name();
    
    /**
     * Specify that the function calls a local named function.
     */
    public void addLocalNamedFunction(String name);

    public void addLocalBoundVariable(String name);

    public void addLocalFreeVariable(String name);


    // Variables: Must be implemented if the function introduces or binds variables
    
    /**
     * The list of all free variables within this function. Ie, the set of all
     * variables contained in the function body that are not bound by a quantifier.
     * In particular, the variable "THIS" is an unbound variable. 
     * @return the list of all free variables
     */
    public List<String> freeVariables();

    /**
     * Does this function or one of its subfunctions call a named function?
     * @return <code>true</code> if a call to an external subfunction is made somewhere
     * within this function, <code>false</code> otherwise.
     */
    public boolean callsNamedFunction();
    
    public boolean isUnary();

    public boolean isConstant();
    
    public String unaryVariable();
    
    public byte height();
    
    public boolean restoreContextState();

    public String toString(String prefix);

    public String toString(String prefix1, String prefix);

    public String toString(String prefix1, String prefix, LocalFunction<?, ?> caller,
        FunctionContext context,
        GraphAccessor accessor);

    public boolean callingToString();

    public void setCallingToString(boolean caughtException);
}
